<!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->
<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<link rel="stylesheet" type="text/css" href="stylesheets/style.css">
<title>EProperties Manual - Introduction</title>
</head>

<body>
<h1><a name="introduction">Introduction</a></h1>
<p> [ <a href="#why">Why?</a> | <a href="#other">Other Extensions/Solutions</a> ] </p>

<p>EProperties (Extended-Properties) extends the function of the standard
<code>java.util.Properties</code> object.</p>
<h3><a name="why">Why?</a></h3>

<p>Why.  It seems a fair question...</p>

<p>Software should be configurable.  As Java developers, writing increasingly
complex software systems, the need for complex configurations has grown and
continues to grow.  Still methods of configuring complex systems are limited
and lacking.  There are two primary methods of configuring complex systems
today: </p>

<h5>Java Properties Files</h5>

<p>Java properties, in the java.util package, provide a simple syntax for 
defining key/value pairs - in many ways the essence of configuration.  Properties
in this form were included in Java 1.0, and except for adding an XML based 
representation, they have not changed since that release.</p>

<p>Drawbacks:</p>
<ul>
  <li>limited to a 'flat' structure</li>
  <li>no means for complex structures</li>
  <li>no support for substitutions</li>
</ul>

<p>Anyone who's seen a complex log4j.properties understands how difficult 
it can be to add structure to simple java.util.Properties files.</p>

<h5>Custom XML Configuration Files</h5>

<p>Many would say that the answer to this lack of capability is using
XML files for configuration.  However this has its drawbacks as well:</p>
<ul>
  <li>Need a new syntax for every configuration option</li>
  <li>verbose and often not suitable for simple configurations</li>
  <li>Not suitable for the many objects/subsystems that already use
      java.util.Properties for configuration.</li>
</ul>

<hr/>

<p>Both of these configuration options seem lacking.  EProperties offers
an alternative with a simple structural extension to the well known
java.util.Properties syntax, while not incurring the inflexibility and verbosity of 
XML based configurations. </p>

<p>EProperties defines a simple, intuitive, lightweight syntax that should
'feel' familiar to an experienced Java developer.  This syntax supports many 
<a href="features.html">features</a> including variable substitution, nesting,
lists, and inclusion.  This syntax and rich feature set frees developers
from the limitations of java.util.Properties, without imposing the overhead 
and limitations of XML based configuration schemes.</p>

<p>EProperties is a simple and powerful means of introducing comprehensive
configuration to very complex systems.</p>

<h3><a name="other">Survey of Other Extensions / Solutions</a></h3>

<p>EProperties is not the first attempt to 'Extend' the existing properties API.
There are other alternatives, and the developer should consider these options
when evaluating EProperties.  We feel after comparison, EProperties can
stand on its rich feature set, focus, and concise API.</p>

<h4>ExtendedProperties in Commons Collections</h4>

<a href="http://commons.apache.org/collections/api-release/org/apache/commons/collections/ExtendedProperties.html">ExtendedProperties</a>

<p>This is a simple - and likely quite useful - extension to the 
Properties object.  Active development seems to have ceased around 2004, 
and it has been replaced by Commons Configuraion.</p>

<h4>Commons Configuration</h4>

<a href="http://commons.apache.org/configuration/">http://commons.apache.org/configuration/</a>

<p>Commons Configuration is a truly comprehensive configuration utility, 
and as its name implies, it is more than simply an extension of the 
java.util.Properites.  This platform supports merging of XML and Properties
based configuration, as well as inclusion and substitution.  And as an Apache
project is merits consideration.  However it seems overly complex, and lacking
focus at times. </p>

</body>
</html>

